3D Graphics Programming with QuickDraw 3D 1.5.4

Reading and Writing File Data

QuickDraw 3D provides routines that you can use to access custom data in a file object. In all cases, the reading or writing occurs at the current file position, and the file position is advanced if the read or write operation completes successfully.

You should call the _Read functions only in a custom read data method (of type kQ3MethodTypeObjectReadData ), and you should call the _Write functions only in a custom write method (of type kQ3MethodTypeObjectWrite ).

These functions can read and write data in either text or binary files.

Q3Uns8_Read

You can use the Q3Uns8_Read function to read an unsigned 8-byte value from a file object.



 
TQ3Status Q3Uns8_Read (TQ3Uns8 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold an unsigned 8-byte value.
file: A file object.

DESCRIPTION

The Q3Uns8_Read function returns, in the block of memory pointed to by the data parameter, the unsigned 8-byte value read from the current position in the file object specified by the file parameter.

Q3Uns8_Write

You can use the Q3Uns8_Write function to write an unsigned 8-byte value to a file object.



 
TQ3Status Q3Uns8_Write (const TQ3Uns8 data, TQ3FileObject file);

data: A pointer to an unsigned 8-byte value.
file: A file object.

DESCRIPTION

The Q3Uns8_Write function writes the unsigned 8-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Int8_Read

You can use the Q3Int8_Read function to read an 8-byte integer value from a file object.



 
TQ3Status Q3Int8_Read (TQ3Int8 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold an 8-byte integer value.
file: A file object.

DESCRIPTION

The Q3Int8_Read function returns, in the block of memory pointed to by the data parameter, the signed 8-byte integer value read from the current position in the file object specified by the file parameter.

Q3Int8_Write

You can use the Q3Int8_Write function to write an 8-byte integer value to a file object.



 
TQ3Status Q3Int8_Write (const TQ3Int8 data, TQ3FileObject file);

data: A pointer to an 8-byte integer value.
file: A file object.

DESCRIPTION

The Q3Int8_Write function writes the signed 8-byte integer value pointed to by the data parameter to the file object specified by the file parameter.

Q3Uns16_Read

You can use the Q3Uns16_Read function to read an unsigned 16-byte value from a file object.



 
TQ3Status Q3Uns16_Read (TQ3Uns16 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold an unsigned 16-byte value.
file: A file object.

DESCRIPTION

The Q3Uns16_Read function returns, in the block of memory pointed to by the data parameter, the unsigned 16-byte value read from the current position in the file object specified by the file parameter.

Q3Uns16_Write

You can use the Q3Uns16_Write function to write an unsigned 16-byte value to a file object.



 
TQ3Status Q3Uns16_Write (const TQ3Uns16 data, TQ3FileObject file);

data: A pointer to an unsigned 16-byte value.
file: A file object.

DESCRIPTION

The Q3Uns16_Write function writes the unsigned 16-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Int16_Read

You can use the Q3Int16_Read function to read a 16-byte integer value from a file object.



 
TQ3Status Q3Int16_Read (TQ3Int16 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold a 16-byte integer value.
file: A file object.

DESCRIPTION

The Q3Int16_Read function returns, in the block of memory pointed to by the data parameter, the signed 16-byte integer value read from the current position in the file object specified by the file parameter.

Q3Int16_Write

You can use the Q3Int16_Write function to write a 16-byte integer value to a file object.



 
TQ3Status Q3Int16_Write (const TQ3Int16 data, TQ3FileObject file);

data: A pointer to a 16-byte integer value.
file: A file object.

DESCRIPTION

The Q3Int16_Write function writes the signed 16-byte integer value pointed to by the data parameter to the file object specified by the file parameter.

Q3Uns32_Read

You can use the Q3Uns32_Read function to read an unsigned 32-byte value from a file object.



 
TQ3Status Q3Uns32_Read (TQ3Uns32 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold an unsigned 32-byte value.
file: A file object.

DESCRIPTION

The Q3Uns32_Read function returns, in the block of memory pointed to by the data parameter, the unsigned 32-byte value read from the current position in the file object specified by the file parameter.

Q3Uns32_Write

You can use the Q3Uns32_Write function to write an unsigned 32-byte value to a file object.



 
TQ3Status Q3Uns32_Write (const TQ3Uns32 data, TQ3FileObject file);

data: A pointer to an unsigned 32-byte value.
file: A file object.

DESCRIPTION

The Q3Uns32_Write function writes the unsigned 32-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Int32_Read

You can use the Q3Int32_Read function to read a signed 32-byte value from a file object.



 
TQ3Status Q3Int32_Read (TQ3Int32 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold a signed 32-byte value.
file: A file object.

DESCRIPTION

The Q3Int32_Read function returns, in the block of memory pointed to by the data parameter, the signed 32-byte value read from the current position in the file object specified by the file parameter.

Q3Int32_Write

You can use the Q3Int32_Write function to write a signed 32-byte value to a file object.



 
TQ3Status Q3Int32_Write (const TQ3Int32 data, TQ3FileObject file);

data: A pointer to a signed 32-byte value.
file: A file object.

DESCRIPTION

The Q3Int32_Write function writes the signed 32-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Uns64_Read

You can use the Q3Uns64_Read function to read an unsigned 64-byte value from a file object.



 
TQ3Status Q3Uns64_Read (TQ3Uns64 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold an unsigned 64-byte value.
file: A file object.

DESCRIPTION

The Q3Uns64_Read function returns, in the block of memory pointed to by the data parameter, the unsigned 64-byte value read from the current position in the file object specified by the file parameter.

Q3Uns64_Write

You can use the Q3Uns64_Write function to write an unsigned 64-byte value to a file object.



 
TQ3Status Q3Uns64_Write (const TQ3Uns64 data, TQ3FileObject file);

data: A pointer to an unsigned 64-byte value.
file: A file object.

DESCRIPTION

The Q3Uns64_Write function writes the unsigned 64-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Int64_Read

You can use the Q3Int64_Read function to read a signed 64-byte value from a file object.



 
TQ3Status Q3Int64_Read (TQ3Int64 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold a signed 64-byte value.
file: A file object.

DESCRIPTION

The Q3Int64_Read function returns, in the block of memory pointed to by the data parameter, the signed 64-byte value read from the current position in the file object specified by the file parameter.

Q3Int64_Write

You can use the Q3Int64_Write function to write a signed 64-byte value to a file object.



 
TQ3Status Q3Int64_Write (const TQ3Int64 data, TQ3FileObject file);

data: A pointer to a signed 64-byte value.
file: A file object.

DESCRIPTION

The Q3Int64_Write function writes the signed 64-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Float32_Read

You can use the Q3Float32_Read function to read a floating-point 32-byte value from a file object.



 
TQ3Status Q3Float32_Read (TQ3Float32 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold a floating-point 32-byte value.
file: A file object.

DESCRIPTION

The Q3Float32_Read function returns, in the block of memory pointed to by the data parameter, the floating-point 32-byte value read from the current position in the file object specified by the file parameter.

Q3Float32_Write

You can use the Q3Float32_Write function to write a floating-point 32-byte value to a file object.



 
TQ3Status Q3Float32_Write (

                     const TQ3Float32 data, 

                     TQ3FileObject file);

data: A pointer to a floating-point 32-byte value.
file: A file object.

DESCRIPTION

The Q3Float32_Write function writes the floating-point 32-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Float64_Read

You can use the Q3Float64_Read function to read a floating-point 64-byte value from a file object.



 
TQ3Status Q3Float64_Read (TQ3Float64 *data, TQ3FileObject file);

data: On entry, a pointer to a block of memory large enough to hold a floating-point 64-byte value.
file: A file object.

DESCRIPTION

The Q3Float64_Read function returns, in the block of memory pointed to by the data parameter, the floating-point 64-byte value read from the current position in the file object specified by the file parameter.

Q3Float64_Write

You can use the Q3Float64_Write function to write a floating-point 64-byte value to a file object.



 
TQ3Status Q3Float64_Write (

                     const TQ3Float64 data, 

                     TQ3FileObject file);

data: A pointer to a floating-point 64-byte value.
file: A file object.

DESCRIPTION

The Q3Float64_Write function writes the floating-point 64-byte value pointed to by the data parameter to the file object specified by the file parameter.

Q3Size_Pad

You can use the Q3Size_Pad function to determine the number of bytes occupied by a longword-aligned block.



 
TQ3Size Q3Size_Pad (TQ3Size size);

size: The size, in bytes, of an object or structure.

DESCRIPTION

The Q3Size_Pad function returns, as its function result, the number of bytes it would take to contain a longword-aligned block whose size, before alignment, is specified by the size parameter.

Q3String_Read

You can use the Q3String_Read function to read a string from a file object.



 
TQ3Status Q3String_Read (

                     char *data, 

                     unsigned long *length, 

                     TQ3FileObject file);

data: On entry, a pointer to a buffer whose length is of size kQ3StringMaximumLength , or NULL . On exit, a pointer to the string read from the specified file object. If this parameter is set to NULL on entry, no string is read, but its length is returned in the length parameter.
length: On exit, the number of characters actually copied into the specified buffer. If data is set to NULL on entry, this parameter returns the length of the string.
file: A file object.

DESCRIPTION

The Q3String_Read function returns, in the data parameter, a pointer to the next string in the file object specified by the file parameter. The string data is 7-bit ASCII, with standard escape sequences for any special characters in the string. The Q3String_Read function also returns, in the length parameter, the length of the string.

Q3String_Write

You can use the Q3String_Write function to write a string to a file object.



 
TQ3Status Q3String_Write (const char *data, TQ3FileObject file);

data: A pointer to a string.
file: A file object.

DESCRIPTION

The Q3String_Write function writes the string data pointed to by the data parameter to the file object specified by the file parameter. The number of bytes written to the file object is equal to Q3Size_Pad(strlen(data)+1) .

Q3NewLine_Write

You can use the Q3NewLine_Write function to write a newline character to a text metafile.



 
TQ3Status Q3NewLine_Write (TQ3FileObject file);

file: A file object.

DESCRIPTION

The Q3NewLine_Write function writes a newline character to the text file object specified by the file parameter. It writes nothing if the file is binary.

Q3RawData_Read

You can use the Q3RawData_Read function to read raw data from a file object.



 
TQ3Status Q3RawData_Read (

                     unsigned char *data, 

                     unsigned long size, 

                     TQ3FileObject file);

data: On entry, a pointer to a buffer whose length is of the specified size. On exit, a pointer to the raw data read from the specified file object.
size: On entry, the number of bytes of raw data to be read from the specified file object into the specified buffer. On exit, the number of bytes actually copied into the specified buffer.
file: A file object.

DESCRIPTION

The Q3RawData_Read function returns, in the data parameter, a pointer to the next size bytes of raw data in the file object specified by the file parameter.

Q3RawData_Write

You can use the Q3RawData_Write function to write raw data to a file object.



 
TQ3Status Q3RawData_Write (

                     const unsigned char *data, 

                     unsigned long size, 

                     TQ3FileObject file);

data: On entry, a pointer to a buffer of raw data whose length is of the specified size.
size: On entry, the number of bytes of raw data to be read from the specified buffer and written to the specified file object. On exit, the number of bytes actually written to the file object.
file: A file object.

DESCRIPTION

The Q3RawData_Write function writes the raw data pointed to by the data parameter to the file object specified by the file parameter. The number of bytes written to the file object is equal to Q3Size_Pad(size) . If the number of bytes written to the file object is greater than size , Q3RawData_Write pads the data to the nearest 4-byte boundary with 0's.

In text files, raw data is output in hexadecimal form.

Q3Point2D_Read

You can use the Q3Point2D_Read function to read a two-dimensional point from a file object.



 
TQ3Status Q3Point2D_Read (

                     TQ3Point2D *point2D, 

                     TQ3FileObject file);

point2D: On entry, a pointer to a block of memory large enough to hold a two-dimensional point.
file: A file object.

DESCRIPTION

The Q3Point2D_Read function returns, in the block of memory pointed to by the point2D parameter, the two-dimensional point read from the current position in the file object specified by the file parameter.

Q3Point2D_Write

You can use the Q3Point2D_Write function to write a two-dimensional point to a file object.



 
TQ3Status Q3Point2D_Write (

                     const TQ3Point2D *point2D, 

                     TQ3FileObject file);

point2D: A pointer to a two-dimensional point.
file: A file object.

DESCRIPTION

The Q3Point2D_Write function writes the two-dimensional point pointed to by the point2D parameter to the file object specified by the file parameter.

Q3Point3D_Read

You can use the Q3Point3D_Read function to read a three-dimensional point from a file object.



 
TQ3Status Q3Point3D_Read (

                     TQ3Point3D *point3D, 

                     TQ3FileObject file);

point3D: On entry, a pointer to a block of memory large enough to hold a three-dimensional point.
file: A file object.

DESCRIPTION

The Q3Point3D_Read function returns, in the block of memory pointed to by the point3D parameter, the three-dimensional point read from the current position in the file object specified by the file parameter.

Q3Point3D_Write

You can use the Q3Point3D_Write function to write a three-dimensional point to a file object.



 
TQ3Status Q3Point3D_Write (

                     const TQ3Point3D *point3D, 

                     TQ3FileObject file);

point3D: A pointer to a three-dimensional point.
file: A file object.

DESCRIPTION

The Q3Point3D_Write function writes the three-dimensional point pointed to by the point3D parameter to the file object specified by the file parameter.

Q3RationalPoint3D_Read

You can use the Q3RationalPoint3D_Read function to read a rational three-dimensional point from a file object.



 
TQ3Status Q3RationalPoint3D_Read (

                     TQ3RationalPoint3D *point3D, 

                     TQ3FileObject file);

point3D: On entry, a pointer to a block of memory large enough to hold a rational three-dimensional point.
file: A file object.

DESCRIPTION

The Q3RationalPoint3D_Read function returns, in the block of memory pointed to by the point3D parameter, the rational three-dimensional point read from the current position in the file object specified by the file parameter.

Q3RationalPoint3D_Write

You can use the Q3RationalPoint3D_Write function to write a rational three-dimensional point to a file object.



 
TQ3Status Q3RationalPoint3D_Write (

                     const TQ3RationalPoint3D *point3D, 

                     TQ3FileObject file);

point3D: A pointer to a rational three-dimensional point.
file: A file object.

DESCRIPTION

The Q3RationalPoint3D_Write function writes the rational three-dimensional point pointed to by the point3D parameter to the file object specified by the file parameter.

Q3RationalPoint4D_Read

You can use the Q3RationalPoint4D_Read function to read a rational four-dimensional point from a file object.



 
TQ3Status Q3RationalPoint4D_Read (

                     TQ3RationalPoint4D *point4D, 

                     TQ3FileObject file);

point4D: On entry, a pointer to a block of memory large enough to hold a rational four-dimensional point.
file: A file object.

DESCRIPTION

The Q3RationalPoint4D_Read function returns, in the block of memory pointed to by the point4D parameter, the rational four-dimensional point read from the current position in the file object specified by the file parameter.

Q3RationalPoint4D_Write

You can use the Q3RationalPoint4D_Write function to write a rational four-dimensional point to a file object.



 
TQ3Status Q3RationalPoint4D_Write (

                     const TQ3RationalPoint4D *point4D, 

                     TQ3FileObject file);

point4D: A pointer to a rational four-dimensional point.
file: A file object.

DESCRIPTION

The Q3RationalPoint4D_Write function writes the rational four-dimensional point pointed to by the point4D parameter to the file object specified by the file parameter.

Q3Vector2D_Read

You can use the Q3Vector2D_Read function to read a two-dimensional vector from a file object.



 
TQ3Status Q3Vector2D_Read (

                     TQ3Vector2D *vector2D, 

                     TQ3FileObject file);

vector2D: On entry, a pointer to a block of memory large enough to hold a two-dimensional vector.
file: A file object.

DESCRIPTION

The Q3Vector2D_Read function returns, in the block of memory pointed to by the vector2D parameter, the two-dimensional vector read from the current position in the file object specified by the file parameter.

Q3Vector2D_Write

You can use the Q3Vector2D_Write function to write a two-dimensional vector to a file object.



 
TQ3Status Q3Vector2D_Write (

                     const TQ3Vector2D *vector2D, 

                     TQ3FileObject file);

vector2D: A pointer to a two-dimensional vector.
file: A file object.

DESCRIPTION

The Q3Vector2D_Write function writes the two-dimensional vector pointed to by the vector2D parameter to the file object specified by the file parameter.

Q3Vector3D_Read

You can use the Q3Vector3D_Read function to read a three-dimensional vector from a file object.



 
TQ3Status Q3Vector3D_Read (

                     TQ3Vector3D *vector3D, 

                     TQ3FileObject file);

vector3D: On entry, a pointer to a block of memory large enough to hold a three-dimensional vector.
file: A file object.

DESCRIPTION

The Q3Vector3D_Read function returns, in the block of memory pointed to by the vector3D parameter, the three-dimensional vector read from the current position in the file object specified by the file parameter.

Q3Vector3D_Write

You can use the Q3Vector3D_Write function to write a three-dimensional vector to a file object.



 
TQ3Status Q3Vector3D_Write (

                     const TQ3Vector3D *vector3D, 

                     TQ3FileObject file);

vector3D: A pointer to a three-dimensional vector.
file: A file object.

DESCRIPTION

The Q3Vector3D_Write function writes the three-dimensional vector pointed to by the vector3D parameter to the file object specified by the file parameter.

Q3Matrix4x4_Read

You can use the Q3Matrix4x4_Read function to read a 4-by-4 matrix from a file object.



 
TQ3Status Q3Matrix4x4_Read (

                     TQ3Matrix4x4 *matrix4x4, 

                     TQ3FileObject file);

matrix4x4: On entry, a pointer to a block of memory large enough to hold a 4-by-4 matrix.
file: A file object.

DESCRIPTION

The Q3Matrix4x4_Read function returns, in the block of memory pointed to by the matrix4x4 parameter, the 4-by-4 matrix read from the current position in the file object specified by the file parameter.

Q3Matrix4x4_Write

You can use the Q3Matrix4x4_Write function to write a 4-by-4 matrix to a file object.



 
TQ3Status Q3Matrix4x4_Write (

                     const TQ3Matrix4x4 *matrix4x4, 

                     TQ3FileObject file);

matrix4x4: A pointer to a 4-by-4 matrix.
file: A file object.

DESCRIPTION

The Q3Matrix4x4_Write function writes the 4-by-4 matrix pointed to by the matrix4x4 parameter to the file object specified by the file parameter.

Q3Tangent2D_Read

You can use the Q3Tangent2D_Read function to read a two-dimensional tangent from a file object.



 
TQ3Status Q3Tangent2D_Read (

                     TQ3Tangent2D *tangent2D, 

                     TQ3FileObject file);

tangent2D: On entry, a pointer to a block of memory large enough to hold a two-dimensional tangent.
file: A file object.

DESCRIPTION

The Q3Tangent2D_Read function returns, in the block of memory pointed to by the tangent2D parameter, the two-dimensional tangent read from the current position in the file object specified by the file parameter.

Q3Tangent2D_Write

You can use the Q3Tangent2D_Write function to write a two-dimensional tangent to a file object.



 
TQ3Status Q3Tangent2D_Write (

                     const TQ3Tangent2D *tangent2D, 

                     TQ3FileObject file);

tangent2D: A pointer to a two-dimensional tangent.
file: A file object.

DESCRIPTION

The Q3Tangent2D_Write function writes the two-dimensional tangent pointed to by the tangent2D parameter to the file object specified by the file parameter.

Q3Tangent3D_Read

You can use the Q3Tangent3D_Read function to read a three-dimensional tangent from a file object.



 
TQ3Status Q3Tangent3D_Read (

                     TQ3Tangent3D *tangent3D, 

                     TQ3FileObject file);

tangent3D: On entry, a pointer to a block of memory large enough to hold a three-dimensional tangent.
file: A file object.

DESCRIPTION

The Q3Tangent3D_Read function returns, in the block of memory pointed to by the tangent3D parameter, the three-dimensional tangent read from the current position in the file object specified by the file parameter.

Q3Tangent3D_Write

You can use the Q3Tangent3D_Write function to write a three-dimensional tangent to a file object.



 
TQ3Status Q3Tangent3D_Write (

                     const TQ3Tangent3D *tangent3D, 

                     TQ3FileObject file);

tangent3D: A pointer to a three-dimensional tangent.
file: A file object.

DESCRIPTION

The Q3Tangent3D_Write function writes the three-dimensional tangent pointed to by the tangent3D parameter to the file object specified by the file parameter.

Q3Comment_Write

You can use the Q3Comment_Write function to write a comment to a file object.



 
TQ3Status Q3Comment_Write (

                     char *comment, 

                     TQ3FileObject file);

comment: A pointer to a null-terminated C string.
file: A file object.

DESCRIPTION

The Q3Comment_Write function writes the string of characters pointed to by the comment parameter to the file object specified by the file parameter. QuickDraw 3D currently supports writing comments to text files only; if you call Q3Comment_Write to write a comment to a binary file, QuickDraw 3D ignores the call. In addition, you cannot currently use QuickDraw 3D to read comments from a file.